---
title: Settings and Secrets
sidebar_position: 9
description: Settings provides a friendly layer to read/write objects from the
    device flash. Keep it small, there's not a lot of space!
---

# Settings

Settings [builtin package](/developer/packages) provides a friendly layer to read/write objects from the device flash. **Keep it small, there's not a lot of space!**

:::tip

In Visual Studio Code, open the command palette and run **DeviceScript: Add Device Settings...**.

:::

## .env files

Don't store secrets or settings in the code, use `.env` files instead.

-   `./.env.defaults`: store general settings (**tracked by version control**)
-   `./.env.local`: store secrets or override for general settings (**untracked by version control**)

The `.env*` file use a similar format to node.js `.env` file. The content will be transfered in the device flash
when deploying the DeviceScript bytecode.

:::caution

The setting keys should be shorter than 14 characters!

:::

```env title="./.env.defaults"
# Default settings
# This file is tracked by git.
# DO NOT store secrets in this file.
temperature=68
```

```env title="./.env.local"
# Local settings and secrets
# This file is/should **NOT** tracked by git
temperature=70 # override
PASSWORD=secret
```

:::tip

In Visual Studio Code, open the command palette and run **DeviceScript: Add Device Settings...**.
From the CLI, run `devs add settings`.

:::

## Special Settings

Some settings entries are treaty specially and routed to other services:

-   `WIFI_SSID`: set the WiFi SSID to connect to
-   `WIFI_PWD`: set the WiFi password (skip or leave empty to connect to open WiFi)

## Using settings

Once your .env files are ready, you can use `readSetting` and `writeSetting` to read/write settings.

```ts
import { Temperature, Button } from "@devicescript/core"
import { readSetting, writeSetting } from "@devicescript/settings"

const temperature = new Temperature()
const button = new Button()
// highlight-next-line
let threshold = await readSetting<number>("temperature")

// show alert when temperature is above threshold
temperature.reading.subscribe(t => {
    // highlight-next-line
    if (t > threshold) {
        // too hot!
        console.log("hot!")
    }
})

// increase threshold when button is pressed
button.down.subscribe(async () => {
    threshold++
    // highlight-next-line
    await writeSetting("temperature", threshold)
})
```

## Clearing

You can use the command **DeviceScript: Clear Device Setings...** to clear the settings
of the currently connected device.

## See also

-   [API reference](/api/settings/)
